Electronic Payment Processing

Important! Please be aware that there are subtle differences between the various Electronic payment gateways. Some settings and characteristics are done in NetForum, some are handled in the gateway merchant account, and some are with the processor you've linked your merchant account to.

This page explains the flow between NetForum and Electronic payment gateways. These details are provided for informational purposes if you want to have a better understanding of the interplay between NetForum and the gateway. You don't need to read this page or understand it in order to set up NetForum, but the information is provided for those with the need or interest to know more what's happening behind the scenes.

Authorization

Every payment begins with an authorization, also commonly known as a pre-authorization.

CVV mismatch

If PaymentProcessCVV is set to required, then immediately following a successful authorization, NetForum checks to see if the gateway reported a CVV mismatch. If a mismatch is reported, then NetForum immediately attempts to void the authorization that was just processed, and return an error number of 199 and an error message of Credit Card Verification Value does not match.

Note: Certain settings need to be configured in NetForum and in your merchant account to enable CVV checks.

Technical note: the action of authorization is represented by Avectra.netForum.Common.TransactionType.PreAuthorization.

Capture

When appropriate, NetForum marks an authorization for capture, also commonly described as post authorization or mark for capture.

By appropriate, we mean that a payment is authorized when it is fulfilled. Most NetForum purchases are fulfilled immediately, such as dues, event registrations, donations, and so on. Some products, however, need to be fulfilled at a later time, such as shippable items. If RecognizeRevenueDuringFulfillment is set to true, then NetForum will not mark a payment for capture until the item is fulfilled.

Also, as described in Avectra.netForum.Common.ICreditCardProcessor, the sequence of doing multiple captures can be complex. Owing to limitations with some electronic payment gateways and the fact that Visa does not allow it, NetForum cannot perform multiple partial captures.

For example, suppose RecognizeRevenueDuringFulfillment is set to true an order is sold that contains two items: a membership for $120 and a shippable book for $25. The total charge is $145. NetForum will do a $145 authorization and, if successful, immediately do a $120 mark-for-capture (PostAuthorization). The remaining $25 of the authorization will not be captured, and will be released by the gateway; when this release occurs is determined by the processor. When the book is fulfilled, NetForum will create a new $25 authorization followed immediately by a $25 mark-for-capture.

Consider a variation of the example above. In this example of purchasing two items, both of which need to be fulfilled. One is a $10 book and the other item is a $20 DVD. On initial purchase, NetForum makes a $30 authorization, with no capture. Suppose the book is fulfilled first.

At that time, NetForum captures the $10. If the capture fails (for example, if the original authorization has lapsed, or is voided in the gateway) then NetForum immediately attempts a new $10 authorization, using the same payment method (and token if applicable) as the original authorization. If the new authorization succeeds, NetForum then attempts to capture the authorization. The remaining $20 is not captured, and will eventually be released by the gateway. It the new authorization or capture is not successful, then the fulfillment process returns an error.

In the gateway, depending on how your processor keeps historical data, you might see that the original authorization lapsed, and that there is a new authorization and capture for the fulfilled amount. In NetForum, you might also see two payments, one for the original amount and a second for the fulfilled amount (which has the authorization code for the second authorization).

If there is a shipping line item in the order, that is for the overall order and not for a line item, then the shipping portion is captured at the time of the first fulfillment.

Technical note: the action of authorization is represented by Avectra.netForum.Common.TransactionType.PostAuthorization.

Capture vs. Mark For Capture

Typically, NetForum will choose the "mark for capture" option with a payment gateway, rather than a full "capture" (often called "force capture"), if the gateway offers the different choices.

Mark for capture allows the gateway to ultimately capture the authorizations upon settlement, whereas force-capture instructs the gateway to capture it right there. Mark for capture is really a way of telling the gateway, "OK, you're good to go, you can settle this when you're ready to". Force capture is a way of telling the gateway, "Capture this in full right now, even before settlement."

Void

Most commonly used to reverse an authorization that was just made.

Technical note: the action of authorization is represented by Avectra.netForum.Common.TransactionType.Void.

Credit

Credits the consumer's account.

Technical note: the action of authorization is represented by Avectra.netForum.Common.TransactionType.Credit.

Sale

Technical note: the action of authorization is represented by Avectra.netForum.Common.TransactionType.Sale.

Inquiry

Technical note: the action of authorization is represented by Avectra.netForum.Common.TransactionType.Inquiry.

Flowcharts

Invoice and Purchase

This depicts what happens when you create and order and apply payment at the same time.

The flowchart is divided into three lanes:

  • Client (left) - this is the actions that occur on the client side, which can be xWeb or an end user in iWeb or eWeb.
  • NetForum application (center) - the middle tier of NetForum where the business logic occurs.
  • Gateway (right) - the actions that occur in the electronic payment gateway.
payment transaction diagram
Electronic payment transaction flowchart.

FAQ

Why Auth/Capture rather than Sale

Q. Why do a separate authorization followed by capture? Why not just do a Sale (which combines the two)?

A. NetForum separates the two to help prevent fragmented transactions between NetForum and the gateway.

Here is the sequence of events. The boxes in the flowchart above are referenced:

  1. NetForum attempts to insert an Invoice (but not yet a payment) as shown in box 2 of the flowchart
  2. If the Invoice is inserted successfully, then attempt a payment Authorization with the gateway (box 6).
    1. If the authorization succeeds, then continue.
    2. If the authorization fails, then rollback the Invoice (box 10)
  3. Attempt to insert a Payment in NetForum (box 12)
    1. If successful, then continue.
    2. If failure, then rollback the invoice (box 14) and attempt to void the authorization (box 15)
  4. If the NetForum Payment insert succeeded, and it is appropriate to issue a capture, then attempt a capture with the gateway (box 19)
    1. If the capture is successful, then continue.
    2. If the capture failed, then rollback the NetForum SQL Transaction containing the Invoice and Payment (box 23) and issue an attempt to void the original authorization with the gateway (box 24)
  5. If the capture succeeded, then commit the NetForum transaction (box 28).

Every effort was made to mitigate the fallout to the end consumer from an unexpected failure at any step along the way. The worse-case scenario is to have a completed sale in the gateway, and no trace of it in NetForum. This means the customer had their card charged but there's no record of the sale in NetForum. The opposite of this scenario is that there is no charge in the gateway, but there is a completed purchase in NetForum; in this scenario, the customer gets the product or service without paying.

The problem with issuing a Sale transaction to the gateway is that if either the invoice or payment failed to insert (in boxes 2 and 12), which can happen in the case of a handled exception such as if a validation failure, or an unexpected exception, it is harder to reverse a Sale than it is to let an Authorization lapse. In the case of a more drastic failure in Insert or Payment, then the Sale could be left hanging. Put another way, issuing a Sale can be risky because there is little room for subsequent mistakes after a successful Sale, but you can "back out" more successfully in the case of submitting separate authorization and captures.

If the call to reverse a Sale fails, or if it cannot be issued, then we are left with the worst-case scenario -- a captured charge in the gateway with no record in NetForum. If, on the other hand, the only transaction in the gateway is an authorization, there is no harm if a later step in NetForum fails and the call to void the authorization fails for some reason (other than the fact that the consumer will have a hanging authorization on their account, which is not ideal, but is not as bad as an inaccurate Sale). Since an authorization will eventually lapse, then there is no significant harm done if the authorization doesn't get voided. If necessary, the authorization can be voided/reversed in the virtual if there is no trace of it in NetForum.

Overall, we took the position that while in theory a Sale transaction has some advantages compared to an Auth+Capture transaction, for defensive reasons we wanted to split these transactions to enable a more graceful handling of exceptions.

Given the volume of financial transactions in NetForum, and the inevitability that some will fail, we wanted to minimize the potential impact to the end consumer.

The other reason NetForum splits the two is because many items in NetForum cannot be fulfilled immediately. For example, if an item is backordered then NetForum will authorize at the point of sale, but delay the capture until the item is actually fulfilled. In this case, a Sale transaction would not be appropriate.

While it would be theoretically possible to code NetForum to do Sale transactions when appropriate, and when not, do an Authorization followed by Capture (when appropriate), we decided to have all transactions go through the same two step process in the interest of consistency and also because of the explanation given at the top of this section.